This document describes the specific functions of the Macintosh version of POV-Ray. It is assumed that you have read (or will read) the POVRAY.DOC file that describes the general operation of POV-Ray. There is also a “POV-Ray 2.x ReadMe” file, which explains the requirements, functionality, and has a brief installation and quick-start section.
Here's a list of topics in this document:
The POV-Ray Preferences dialog, up close
The Rendering Options dialog, up close
The Animation Settings dialog, up close
Advanced Tips
To speed up rendering as much as possible…
To edit large scene files…
To batch-render a series of individual scene files…
To generate a QuickTime movie from POV-Ray…
Bugs, Quirks, and Future Directions
The Bad News...
The Good News, Coming sometime after version 2.0...
The Source Code
Think C Compiler Notes
MPW C Compiler Notes
The POV-Ray Preferences dialog, up close
-------------------------------------
This dialog sets up general preferences for the POV-Ray application that will be remembered between renders, and between separate runs of POV-Ray itself. Here is a description of what each item does:
(1) Application Friendliness - The higher the number, the more time POV-Ray takes from other applications, and the faster it runs (and the slower and more jumpy the other applications become.)
(2a) Use Application's Default Rendering Options - To use the Application Default Rendering Options for rendering files (ignoring each file's unique Rendering Options), click here. This is normally used for multiple rendering sessions.
(2b) Use each file's Rendering Options - To use each file's unique Rendering Options, click here. This is normally used for single rendering sessions.
(3a) Notify When Complete - Select one of these items to tell POV-Ray what to do when it finishes rendering the scene or scenes. It can finish quietly or it can notify you. 4b below lets you set HOW it notifies you.
(3b) Notification Style - Select one of these items to tell POV-Ray how to notify you when it finishes rendering the scene or scenes. It can either beep, display a dialog, or do both.
(4) Set Include Folder - Click this button to choose which folder POV-Ray should look in for files specified in the "#include" statements. It will also look in the same folder as the original scene being rendered. Just below this button is the path to the current folder it will look in.
The Rendering Options dialog, up close
----------------------------------
This dialog sets up specific rendering options for the current scene file. These options are stored with the scene file itself (in the respurce fork) and are remembered on subsequent renders of the scene file. Here is a description of what each item does:
(1a) Preset Image Sizes - Selecting an image size here will automatically fill in the width/height/from/to fields below with a preset size. Many screen sizes are listed here.
(1b) Width - Enter the total width of the image you want to render (in pixels.) This number can be from 1 to 4096.
(1c) Height - Enter the total height of the image you want to render (in pixels.) This number can be from 1 to 4096.
(1d) From row - Enter the top scanline, or starting row, of the image you want to render (in pixels.) Only enter a number here if you want to render a partial image.
(1e) To row - Enter the bottom scanline, or ending row, of the image you want to render (in pixels.) Only enter a number here if you want to render a partial image.
(2) Progress - Sets how much information is displayed in the status window as the render progresses. "No Info" is quiet, "Minimal Info" shows some memory usage information, "Progress Info" informs you of each scanline, "Debug Info" shows internal debug information. See POVRAY.DOC for more information on the "+V" option.
(3) Image Quality - Enter a number (from zero to nine) to select the quality of the rendered image. 1 just shows grey shapes, 5 shows colors, 9 shows full shadows lights and refraction. The lower the number, the lower the quality and the faster the render.See POVRAY.DOC for more information on the "+Q" option.
(4) Auto-bounding - Turn this popup on to let POV-Ray optimize your scene by automatically "bounding" the objects in your scene. The number you set is the minimum number of main objects it finds before it decides to kick in auto-bounding. See POVRAY.DOC for more information on the "+MB" option.
(5a) Animate - Turn this on if you want to create a sequence of multiple images from this scene file. See POVRAY.DOC for more information on the "+K" option.
(5b) Animate Settings - Click this to set up the number of frames, clock value range, etc. for animation.
(6) Language - Set this to which version of POV-Ray syntax this file is written in (version 1.0 or 2.0.) See POVRAY.DOC for more information on the "+MV" option.
(7a) Compress Image - Turn this on to automatically use QuickTime image compression on the output PICT file when it is saved.
(7b) Compression Settings - Click this to set up what kind of image compression to use on the PICT file.
(8) Max Symbols - Set this to the largest number of #declared items in your scene file. See POVRAY.DOC for more information on the "+MS" option.
(9a) Do Anti-aliasing - Click here to toggle “anti-aliasing” of the image. Although the rendering can take much longer when this is on, the final image is much nicer looking, with fewer jagged edges. See POVRAY.DOC for more information on the "+A" option.
(9b) Threshold - Enter a number here (from 0.0 to 1.0) that determines the threshold depth of anti-aliasing. The closer to 0.0, the more anti-aliasing is done, the better the image looks, and the longer it takes to render.
(9c) Depth - Enter a number from 1 to 9 here to set the recursive depth of anti-aliasing. The number of rays is the square of this number, so a 3 would create 3*3 or 9 rays, etc.
(9d) Jitter - Enter a number from 0.0 (no jitter) through 1.0 (lots of jitter.) The higher this number, the "wider" the anti-aliasing area, and the smoother it looks.
(10a) Create Targa Output File - To toggle the creation of a Targa-format output file during the render process, click here. This can allow you to stop POV-Ray partway through, and run it later to finish from where it left off.
(10b) Continue Rendering with Targa - To tell POV-Ray to load the Targa file from the previous run and to continue where it left off last, click here.
(11) Save as defaults for new files - To save the current Rendering Option Settings as the Application's Default Settings, click here. All new documents will then acquire these default Rendering Options.
The Animation Settings dialog, up close
----------------------------------
This dialog sets up how many frames of animation to generate, and how the clock variable should change across the frames. Note the outer bounds (Initial and Final) are used for calculating the overall number of frames and values for the scene. The inner bounds (Start at and End at) are used to determine which frames to actually generate for this session. Here is a description of what each item does:
*** Frame Number. This is just a reference number which counts the number of frames (or images) to generate. It starts at one, and increments for each frame.
(1a) Initial - This is a constant low bound for the frame counter. It is always one.
(1b) Start At - This is the first frame number to start generating images for. It can be any integer number from "Initial" to "End at".
(1c) End At - This is the last frame number to generate images for. It can be any integer number from "End at" to "Final".
(1d) Final - This is the high bound for the frame counter. It is the total number of frames that should be generated for the scene. This is used to calculate the span of clock values.
*** Clock Value. plication heap size. This was addressed prior to release, but not all leaks were found... it will be completely fixed in a future release. All "direct" memory leaks are fixed, what's left seems to be caused by calling runtime routines that themselves leak.
* POV-Ray should be creating the POV-Ray Virtual Image Buffer file in the Temporary Items folder if it is running under System 7, it currently does not.
* There is still an occasional quirk in the vertical scrollbar of the Status window, where it will get out of sync if you scroll it while the window is being filled. Nothing is lost, and if you scroll to the top and back to the bottom, all returns to normal.
* There are reports that the "Finder Balloon Help" of the POV-Ray Application (turn on Balloon Help and point at app in the Finder) does not work on some Macs. It will report a Finder "Type -192" error. It seems to work properly on other machines. This may be due to a corrupt desktop database, although rebuilding the desktop was reported not to help.
* Under System 6.x, POV-Ray will not automatically open a document that is double clicked from the Finder. You must run POV-Ray, then open the file from the File menu. Double-clicking documents DOES work properly in System 7, and in fact, multiple file drag-n-drop is supported. This missing System 6 feature was an intentional omission due to time constraints and the low priority of the feature.
* If you are using a virtual image buffer for a large image, it is not advisable to use the "Size Image to Window" mode, because the image won't display properly. This is only a display problem, It will save properly when finished.
* Adobe Photoshop prior to version 2.5 ignores the vertical-flipped bit of the TARGA files created by POV-Ray, and displays them upside down. Version 2.5 fixes this problem.
* With System 7 Virtual Memory (VM) on, and anti-alias setting on, and an anti-alias on, the VM file will do some thrashing occasionally if your rendering requires a virtual image buffer. This will just slow things way down; it doesn't cause any crashes.
The Good News, Coming sometime after version 2.0...
*****************************************
* Allow selecting an arbitrary area in Image window, and then re-rendering just that area (x1,y1 to x2,y2).. more flexible than the current start/end scanline method
* Allow user to scroll the Image window
* Let user pick file signature for PICT and Targa file formats. Currently, PICT files are saved with TeachText's signature and Targa files are saved with PhotoShop's (PICT creator type is currently saved in scene file's fPrf resource, & could be edited with ResEdit.)
* Built-in QuickTime movie support
* TIFF and PICT image (image-map) support for POV-Ray
* TrueType font support (extruded characters.. need generic POV-Ray syntax additions for typeface import?)
* Allow saving image directly to GIF or 8 bit Mac PICT format (currently just 24 bit PICT now.)
* Mac Network (distributed) rendering
The Mac Source Editor needs a _major_ facelift, to include:
* Abandon stock TextEdit, support source files larger than 32K chars
* Support tabs
* Search and replace features should be added
* Shape prototype generation, esp. torus and other tough ones
* Add balanced curly brace checking
* Simultaneously edit multiple source files, useful for Includes
One possible way to enhance the editor is to give up on the built-in text editor altogether, and tell the user to use BBEdit or some other text editor, and we could break POV-Ray into a faceless rendering engine that accepts AppleEvents. The options dialogs could be supported by a stand-alone application that could alter the file's settings prior to rendering. This makes POV-Ray more loosely coupled, but paves the way for drop-in editors and network rendering. Besides the time it would take to do this, an interesting obstacle to overcome is how the rendering engine would display its image. If it was not so tightly integrated, quick changes and re-rendering sessions may be more awkward. These are some interesting ideas... we are interested in hearing from users as to which way future versions of POV-Ray should head, let us know!
The Source Code
---------------
POV-Ray is a team effort, and the team members use Compuserve's Graphics Developers forum (GRAPHDEV) to keep abreast of changes and suggestions. Before you dive in and write massive enhancements, we suggest that you contact any of the team members and get to know the guidelines. We are an easy going bunch, and very friendly and interested in helping newcomers. And who knows, we may be working on the very same features you want to add, or your enhancement may be one we're hoping to see done. If you wish to make changes to POV-Ray, read the Port Guide, found in the POVSRC archive under MISC:PORTGUID.DOC.
Before you publically post altered source or executables, please review the POV-Ray legal documentation for copyright restrictions and rules of distribution. POVLEGAL.DOC can be found in any of the archives. To restate our position: please contact us directly with any bug fixes or enhancements. We can then incorporate them into the next general release.
The executables released by the POV Team for the Macintosh are built using Think C 6.0. It is possible to create even faster POV-Ray executables using a mix of Gnu C and MPW, but for a straight compilation, Think C 6.0 is a little smaller and faster than MPW 3.2 or MPW 3.3.
You will find the source code in two sections in the POVSRC archive. The main portion of POV-Ray is in POVSRC:SOURCE:. The additional Macintosh-specific source code is in POVSRC:MACHINE:MAC-Source:. These two sets of source should then be put together into a single POV-Ray Source folder before building (any name is fine.)
Some Apple header files for QuickTime compression are also included. These are mainly for the Think C 5 & 6 environment, as they are already present in MPW 3.3. If you're trying to build a version and add newer QuickTime features (1.61 is current as of this release), you may need to get newer header files from Apple or Symantec, or whoever is doing Apple's development system these days :-)
Think C Compiler Notes
------------------------
When compiling, you must use Think C 5.0 or later (preferably 5.0.4 or 6.0.) The enclosed Project file "POV.π" is for Think C 6.0. To compile under Think C 5.x, you will need to throw this file away and create a new one from scratch. Notes on how to do this are listed below.
Think C 5 & 6 don't have the following QuickTime headers, so we have provided them for now. You will need to copy them into Think C's "Apple Includes" folder.
ImageCodec.h
ImageCompression.h
MediaHandlers.h
Movies.h
MoviesFormat.h
QuickTimeComponents.h
You should first make a COPY of your "Standard Libraries:ANSI" library's Project file, and rename your copy to “ANSI-020.FPU.NoConsole”. This will be the ANSI library you'll be using for POV-Ray. Remove the files "console.c" and "command.c" from the project. Choose the Edit:Options menu, and change the following: Think C:Compiler settings, turn on all checkboxes except "4 byte ints" and "8 byte Doubles". Code Optimizations:turn on all, but not the Global Optimizations. Debugging:turn off all. Prefix:add a #define _NOCONSOLE_. Choose the menu Project:Set Project Type, and turn on "Separate Strs". Now "update" to compile all the modules.
For Think C 5 users, there are some additional steps, to create the POV.π project file from scratch. Start up Think C, create a new project called POV.π, and add all the .c source files to the project. Here's the current segmenting strategy:
